rustdoc: properly support macros with multiple kinds by GuillaumeGomez · Pull Request #152449 · rust-lang/rust

GuillaumeGomez · 2026-02-10T18:09:21Z

Since it seems like I can't reopen #145458, opening this one. Although, it's the same PR minus the last new commit to handle a comment that was left unresolved in the original PR. All relevant details are still in the original PR though.

It's an alternative (and likely a take-over) of #148005 since lang-team rejected the idea to add documentation on macro branches, making the multiple files approach less suitable.

This implements #145153 in rustdoc. This PR voluntarily doesn't touch anything related to intra-doc links, I'll send a follow-up if needed.

So now about the implementation itself: this is a weird case where a macro can be different things at once but still only gets one file generated. I saw two ways to implement this:

Handle ItemKind::Macro differently and iter through its MacroKinds values.
Add new placeholder variants in the ItemKind enum, which means that when we encounter them in rendering, we need to ignore them. It also makes the ItemKind enum bigger (and also needs more code to be handled). Another downside is that it needs to be handled in the JSON output.

Now there was an interesting improvement that came with this PR in the html::render::print_item::item_module function: I simplified its implementation and split the different parts in a HashMap where the key is the item type. So then, we can just iterate through the keys and open/close the section at each iteration instead of keeping an Option<section> around.

From RFCs:

derive:

attr:

both:

r? @notriddle

rustbot · 2026-02-10T18:09:24Z

Some changes occurred in HTML/CSS/JS.

cc @lolbinarycat

GuillaumeGomez · 2026-02-10T20:25:32Z

Oh and also cc @lolbinarycat as you reviewed the original PR too. :)

GuillaumeGomez · 2026-02-20T12:05:34Z

Fixed merge conflicts.

lolbinarycat · 2026-04-06T19:27:23Z

blocking this on #154902, since that relies on bang macro === macro_rules macro.

Rename `ItemType::BangMacro*` into `ItemType::DeclMacro*` Rename `isBangMacro` field into `forceMacroHref`

Add more typescript type annotations Improve functions naming

rustbot · 2026-05-10T00:44:55Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

GuillaumeGomez · 2026-05-10T00:45:19Z

Needed to rebase because some changes were incompatible.

lolbinarycat

the search related code doesn't make sense to me anymore.

View changes since this review

lolbinarycat · 2026-05-12T18:14:57Z

+    /// for `macro_rules!` items which contain an attr/derive kind.
+    pub(crate) fn types(&self) -> impl Iterator<Item = ItemType> {
+        if let ItemKind::MacroItem(_, macro_kinds) = self.kind {
+            Either::Right(macro_kinds.iter().map(|kind| match kind {


Hey using macro_kinds.iter() here means the order of the iterator depends on bitflags iteration order, which I don't love.

As far as I know, the order never matters since it's the same item with potentially different types.

lolbinarycat · 2026-05-12T18:24:22Z

+
+#![feature(macro_attr)]
+#![feature(macro_derive)]
+


I think we're missing a testcase:

#[macro_export] macro_rules! macro5 { attr() () => {}; derive() () => {}; }

Indeed, adding it.

GuillaumeGomez · 2026-05-12T22:37:53Z

Added the missing test case, also improved the search code clarity a bit.

lolbinarycat

Alright, I think it's ready, lets try this.

@bors r=lolbinarycat,mejrs

View changes since this review

lolbinarycat · 2026-05-16T18:05:49Z

+            let tag = if my_section == super::ItemSection::Reexports {
+                REEXPORTS_TABLE_OPEN
+            } else {
+                ITEM_TABLE_OPEN
+            };
+            write!(
+                w,
+                "{}",
+                write_section_heading(my_section.name(), &cx.derive_id(my_section.id()), None, tag)
+            )?;


This refactor made me realize there's no snapshot test for sidebar generation. I think I'll submit a PR for that.

rust-bors · 2026-05-16T18:12:45Z

📌 Commit 376e0c0 has been approved by lolbinarycat,mejrs

It is now in the queue for this repository.

🌲 The tree is currently closed for pull requests below priority 100. This pull request will be tested once the tree is reopened.

rust-bors · 2026-05-16T22:13:55Z

☀️ Test successful - CI
Approved by: lolbinarycat,mejrs
Duration: 3h 19m 7s
Pushing d3cd040 to main...

github-actions · 2026-05-16T22:16:41Z

What is this?

This is an experimental post-merge analysis report that shows differences in test outcomes between the merged PR and its parent PR.

Comparing be326a9 (parent) -> d3cd040 (this PR)

Test differences

Show 16 test diffs

Stage 1

[rustdoc-html] tests/rustdoc-html/macro/decl_macro-sidebar.rs: [missing] -> pass (J1)
[rustdoc-html] tests/rustdoc-html/macro/macro-attr-derive.rs: [missing] -> pass (J1)
[rustdoc-html] tests/rustdoc-html/macro/macro-attr.rs: [missing] -> pass (J1)
[rustdoc-html] tests/rustdoc-html/macro/macro-derive.rs: [missing] -> pass (J1)
[rustdoc-html] tests/rustdoc-html/macro/macro-no-bang.rs: [missing] -> pass (J1)
[rustdoc-js] tests/rustdoc-js/macro-kinds.rs: [missing] -> pass (J1)

Stage 2

[rustdoc-html] tests/rustdoc-html/macro/decl_macro-sidebar.rs: [missing] -> pass (J0)
[rustdoc-html] tests/rustdoc-html/macro/macro-attr-derive.rs: [missing] -> pass (J0)
[rustdoc-html] tests/rustdoc-html/macro/macro-attr.rs: [missing] -> pass (J0)
[rustdoc-html] tests/rustdoc-html/macro/macro-derive.rs: [missing] -> pass (J0)
[rustdoc-html] tests/rustdoc-html/macro/macro-no-bang.rs: [missing] -> pass (J0)
[rustdoc-js] tests/rustdoc-js/macro-kinds.rs: [missing] -> pass (J2)

Additionally, 4 doctest diffs were found. These are ignored, as they are noisy.

Job group index

Test dashboard

Run

cargo run --manifest-path src/ci/citool/Cargo.toml -- \
    test-dashboard d3cd04068e406dd961c2fd666c049c3e38930e0a --output-dir test-dashboard

And then open test-dashboard/index.html in your browser to see an overview of all executed tests.

Job duration changes

dist-x86_64-llvm-mingw: 1h 30m -> 2h 1m (+33.8%)
x86_64-mingw-1: 2h 14m -> 2h 56m (+31.5%)
dist-x86_64-solaris: 1h 17m -> 1h 37m (+26.5%)
dist-ohos-armv7: 1h 1m -> 1h 12m (+19.0%)
dist-ohos-x86_64: 1h 17m -> 1h 3m (-18.5%)
dist-riscv64-linux: 1h 28m -> 1h 12m (-17.4%)
dist-ohos-aarch64: 1h 16m -> 1h 3m (-17.4%)
dist-armhf-linux: 1h 25m -> 1h 11m (-16.3%)
dist-various-2: 42m 50s -> 35m 54s (-16.2%)
i686-gnu-1: 2h 27m -> 2h 4m (-15.7%)

How to interpret the job duration changes?

Job durations can vary a lot, based on the actual runner instance
that executed the job, system noise, invalidated caches, etc. The table above is provided
mostly for t-infra members, for simpler debugging of potential CI slow-downs.

rust-timer · 2026-05-16T22:56:10Z

Finished benchmarking commit (d3cd040): comparison URL.

Overall result: ❌✅ regressions and improvements - please read:

Our benchmarks found a performance regression caused by this PR.
This might be an actual regression, but it can also be just noise.

Next Steps:

If the regression was expected or you think it can be justified,
please write a comment with sufficient written justification, and add
@rustbot label: +perf-regression-triaged to it, to mark the regression as triaged.
If you think that you know of a way to resolve the regression, try to create
a new PR with a fix for the regression.
If you do not understand the regression or you think that it is just noise,
you can ask the @rust-lang/wg-compiler-performance working group for help (members of this group
were already notified of this PR).

@rustbot label: +perf-regression
cc @rust-lang/wg-compiler-performance

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	0.3%	[0.3%, 0.3%]	1
Regressions ❌ (secondary)	0.3%	[0.3%, 0.3%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-0.1%	[-0.1%, -0.1%]	1
All ❌✅ (primary)	0.3%	[0.3%, 0.3%]	1

Max RSS (memory usage)

Results (primary 2.8%, secondary 2.9%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	2.8%	[2.0%, 3.7%]	2
Regressions ❌ (secondary)	2.9%	[2.9%, 2.9%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	2.8%	[2.0%, 3.7%]	2

Cycles

Results (secondary 3.4%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	3.4%	[3.4%, 3.4%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-	-	0

Binary size

This perf run didn't have relevant results for this metric.

Bootstrap: 511.489s -> 510.352s (-0.22%)
Artifact size: 400.43 MiB -> 398.50 MiB (-0.48%)

GuillaumeGomez · 2026-05-16T22:58:08Z

The impact is expected since we added some loops for iterating types for an item (even though 99.9% of the time, there is only one type).

rust-log-analyzer · 2026-05-17T00:50:55Z

A job failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

  COMMIT_MESSAGE: cargo update 
##[endgroup]
Downloading single artifact
Preparing to download the following artifacts:
- Cargo-lock (ID: 7038012302, Size: 50955, Expected Digest: sha256:1ec39f6d7e9e7782368b9033ab292975a40e50e65bd3ecaf98d43ad99fa93c0c)
Redirecting to blob download url: https://productionresultssa13.blob.core.windows.net/actions-results/fbf68af5-8a38-4a41-a946-3f809ed77539/workflow-job-run-8d8e9bf0-8184-58ce-a8f2-9d3bd4c2d29d/artifacts/858175980ba8726bab9f963fd06060d5199d874bbd735e523e2d990d354f8c0b.zip
Starting download of artifact to: /home/runner/work/rust/rust
(node:2274) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
SHA256 digest of downloaded artifact is 1ec39f6d7e9e7782368b9033ab292975a40e50e65bd3ecaf98d43ad99fa93c0c
Artifact download completed successfully.
Total of 1 artifact(s) downloaded
Download artifact has finished successfully
---
  COMMIT_MESSAGE: cargo update 
##[endgroup]
Downloading single artifact
Preparing to download the following artifacts:
- cargo-updates (ID: 7038012344, Size: 2684, Expected Digest: sha256:d406285453990ba8d3d772b890e8fa5aee17468bb7a7ff0fa62bbf4afe4e2ab6)
Redirecting to blob download url: https://productionresultssa13.blob.core.windows.net/actions-results/fbf68af5-8a38-4a41-a946-3f809ed77539/workflow-job-run-8d8e9bf0-8184-58ce-a8f2-9d3bd4c2d29d/artifacts/ce9034d4568b3430f906da1368ae1cf3e14ef1542859eb2e8d635c0876371f53.zip
Starting download of artifact to: /home/runner/work/rust/rust
(node:2286) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
SHA256 digest of downloaded artifact is d406285453990ba8d3d772b890e8fa5aee17468bb7a7ff0fa62bbf4afe4e2ab6
Artifact download completed successfully.
Total of 1 artifact(s) downloaded
Download artifact has finished successfully
##[group]Run echo "${COMMIT_MESSAGE}" > commit.txt
echo "${COMMIT_MESSAGE}" > commit.txt
cat cargo_update.log >> commit.txt

echo "${PR_MESSAGE}" > body.md
echo '```txt' >> body.md
cat cargo_update.log >> body.md
echo '```' >> body.md
shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}
---
dep-bumps
following is the output from `cargo update`:
  COMMIT_MESSAGE: cargo update 
##[endgroup]
##[group]Run git config user.name github-actions
git config user.name github-actions
git config user.email github-actions@github.com
git switch --force-create cargo_update
git add ./Cargo.lock ./library/Cargo.lock ./src/tools/rustbook/Cargo.lock
git commit --no-verify --file=commit.txt
shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}
---
dep-bumps
following is the output from `cargo update`:
  COMMIT_MESSAGE: cargo update 
##[endgroup]
remote: error: GH013: Repository rule violations found for refs/heads/cargo_update.        
remote: Review all repository rules at https://github.com/rust-lang/rust/rules?ref=refs%2Fheads%2Fcargo_update        
remote: 
remote: - Cannot update this protected ref.        
remote: 
remote: - Changes must be made through a pull request.        
remote: 
remote: - Cannot force-push to this branch        
remote: 
To https://github.com/rust-lang/rust
 ! [remote rejected]   cargo_update -> cargo_update (push declined due to repository rule violations)
error: failed to push some refs to 'https://github.com/rust-lang/rust'
##[error]Process completed with exit code 1.
Post job cleanup.

rustbot assigned notriddle Feb 10, 2026

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from 20f13be to 4b35c49 Compare February 10, 2026 18:18

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from 4b35c49 to 4416897 Compare February 10, 2026 20:25

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from 4416897 to be7815f Compare February 10, 2026 20:41

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from be7815f to 3e05767 Compare February 20, 2026 12:05

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from 3e05767 to ce98d4e Compare April 7, 2026 16:31

This comment has been minimized.

Sign in to view

mejrs reviewed Apr 7, 2026

View reviewed changes

Comment thread tests/rustdoc-gui/src/test_docs/macros.rs Outdated

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from ce98d4e to 5ada01c Compare April 7, 2026 22:44

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from 5ada01c to 26f32d9 Compare April 17, 2026 23:13

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch 2 times, most recently from eef2a58 to cbe154c Compare April 18, 2026 15:46

GuillaumeGomez and others added 6 commits May 10, 2026 02:37

Handle new kinds of macros at once

9b2fecb

Simplify bang macro handling by merging all into one type

28cfe80

Correctly generate bang macro declaration in docs for attr/derive kinds

d0ff143

Improve code and docs

daec3d8

Change HTML IDs for attribute macros and attributes

1cbb922

Rename `ItemType::BangMacro*` into `ItemType::DeclMacro*` Rename `isBangMacro` field into `forceMacroHref`

Replace "bang macro" mentions with "decl macro"

794301a

Add more typescript type annotations Improve functions naming

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from 718a495 to 794301a Compare May 10, 2026 00:44

lolbinarycat changed the title ~~Rustdoc bang attr macro~~ rustdoc: properly support macros with multiple kinds May 12, 2026

lolbinarycat reviewed May 12, 2026

View reviewed changes

Improve search.js code readability and add missing test case

376e0c0

lolbinarycat approved these changes May 16, 2026

View reviewed changes

rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels May 16, 2026

This comment has been minimized.

Sign in to view

rust-bors Bot added merged-by-bors This PR was explicitly merged by bors. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels May 16, 2026

rust-bors Bot merged commit d3cd040 into rust-lang:main May 16, 2026
12 checks passed

rustbot added this to the 1.97.0 milestone May 16, 2026

GuillaumeGomez deleted the rustdoc-bang-attr-macro branch May 16, 2026 22:14

rustbot added the perf-regression Performance regression. label May 16, 2026

GuillaumeGomez added the perf-regression-triaged The performance regression has been triaged. label May 16, 2026


		#![feature(macro_attr)]
		#![feature(macro_derive)]

Uh oh!

Conversation

GuillaumeGomez commented Feb 10, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Feb 10, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Feb 10, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Feb 20, 2026

Uh oh!

This comment has been minimized.

lolbinarycat commented Apr 6, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

Uh oh!

This comment has been minimized.

rustbot commented May 10, 2026

Uh oh!

GuillaumeGomez commented May 10, 2026

Uh oh!

lolbinarycat left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GuillaumeGomez commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lolbinarycat left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rust-bors Bot commented May 16, 2026

Uh oh!

This comment has been minimized.

rust-bors Bot commented May 16, 2026

Uh oh!

Uh oh!

github-actions Bot commented May 16, 2026

Test differences

Stage 1

Stage 2

Job duration changes

Uh oh!

rust-timer commented May 16, 2026

Overall result: ❌✅ regressions and improvements - please read:

Uh oh!

GuillaumeGomez commented May 16, 2026

Uh oh!

rust-log-analyzer commented May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

GuillaumeGomez commented Feb 10, 2026 •

edited by rustbot

Loading

lolbinarycat left a comment •

edited

Loading

GuillaumeGomez commented May 12, 2026 •

edited

Loading

lolbinarycat left a comment •

edited by rustbot

Loading